home *** CD-ROM | disk | FTP | other *** search
/ System Booster / System Booster.iso / Archives / ForCLI / scan082.lha / scan.readme < prev    next >
Text File  |  1992-04-03  |  17KB  |  362 lines
  1.  
  2.    Program: Scan
  3.  
  4.    Version: 0.82 gamma 4/02/92
  5.  
  6.    Utility: Searches twice as fast on hard drives and five times faster
  7.             in ram than the best search programs currently available.
  8.  
  9.             Option to scan selective(wildcard) internal LZH and LHA files
  10.  
  11.             Supports searching for multiple patterns simultaneously
  12.             with little speed degradation.
  13.  
  14.             Option to output whole article when a match is found.
  15.  
  16.             Extensive wildcard support(*,?,[],[^],[-],+,|,&,..).
  17.  
  18.             Optional inverted pattern matching.
  19.  
  20.             Recursive directory scanning.
  21.  
  22.             Support for \x?? and \? in patterns and article separator.
  23.  
  24.             Line search highlights matching words with selectable color.
  25.  
  26.             Freeware.
  27.  
  28.    Tribute: Eternal praise to Jesus for saving my soul and for the wonders
  29.             of God's creation.
  30.  
  31.    Legal:   Copyright © 1991, 1992 by Walter Rothe
  32.  
  33.             This program is freely distributable, but copyrighted by me. This
  34.             means that you can copy it freely as long as you don't ask for any
  35.             more money than a nominal fee for copying. This program may be
  36.             placed on Public Domain disks, like Fred Fish's library. To
  37.             distribute this program you must include the program,
  38.             documentation, and test files in their original unmodified form.
  39.             This does not preclude compression by archiving programs like
  40.             lharc. This program cannot be used for commercial purposes
  41.             without written permission from the author. The author can not
  42.             be made responsible for any damage which is caused by using
  43.             this program.
  44.  
  45.    Command: Scan -[nprt] -[hColor] -[lNumLines] -[wWinSize] -[oOutFile]
  46.    format        -[zLHAWild] SrchFile(s) Pattern
  47.  
  48.                               OR
  49.  
  50.             Scan -f[CnfgFile] -[oOutFile] -[pr] -[zLHAWild] SrchFile(s)
  51.  
  52.                               OR
  53.  
  54.             Scan -a[ipr] [-cColumn] -[sArtSep] -[oOutFile] -[wWinSize]
  55.                  -[zLHAWild] SrchFile(s) Pattern
  56.  
  57.                               OR
  58.  
  59.             Scan -[vx]
  60.  
  61.    Names:   Color       - A two digit number, where the 1st number indicates
  62.                           the color the matching word is highlighted with,
  63.                           and the second is the color the filenames of the
  64.                           files being searched are highlighted with. Currently
  65.                           limited to 0-9.
  66.  
  67.             NumLines    - Number of lines of context information printed
  68.                           around match.
  69.  
  70.             WinSize     - Number of bytes in window. Default 16K bytes.
  71.                           Modulus( WinSize, 4 ) must be 0. There are
  72.                           three buffers, each WinSize long that are swapped.
  73.                           Larger size windows usually increase the speed,
  74.                           except when handling large numbers of small files.
  75.                           Also, the larger the window, the more context
  76.                           information can be printed. Context info is limited
  77.                           to whats in the present and previous buffer. Large
  78.                           article may need a large window to be fully printed
  79.                           out. Currently the WinSize is forced to 16kb
  80.                           whenever the -z option is in effect.
  81.  
  82.             OutFile     - Pathname of file output will be put into.
  83.  
  84.             LHAWild     - Wildcard pattern that is used to determine which
  85.                           internal LHA files are scanned. Only "*" and "?"
  86.                           wildcards are permitted here. Note that the full
  87.                           internal filename must be matched. Any directories
  88.                           must be included. Some shells expand wildcards on
  89.                           the command line so you may need to enclose the
  90.                           option with quotes. i.e. "-z*.c"
  91.  
  92.             SrchFile(s) - Pathname of file(s) to be searched. Only "*" and "?"
  93.                           wildcards are permited here. For recursive dir
  94.                           scans, you need only specify the directory pathname.
  95.                           You can optionally add a "/" or "/*.h" to the end of
  96.                           the directory pathname. The command line is limited
  97.                           to 255 chars so if you specify a wildcard pattern and
  98.                           the pathnames of the matching files exceed 255 chars,
  99.                           the last files wont be scanned. To get around this,
  100.                           enclose the wildcard with quotes. i.e. "*.l??"
  101.  
  102.             Pattern     - Pattern to search for. This can include the
  103.                           wildcards "*", "?", "&", "|", "+", and "..". Refer to
  104.                           the following section on pattern matching. Note that
  105.                           you may need to enclose some of the wildcards in
  106.                           quotes to keep the shell from expanding them. Also,
  107.                           there must be at least 2 consequtive unique non
  108.                           wildcard characters in each pattern between the
  109.                           "|" wildcards. Pattern is case insensitive. For
  110.                           example "sale..d*paint[3i]|paint&prog"
  111.  
  112.             CnfgFile    - Pathname of file containing article separator,
  113.                           column for article separator, inversion flag,
  114.                           window size, and search pattern with each on a
  115.                           separate line, starting in column 1. Note that each
  116.                           pattern between "|"'s appears on a separate line
  117.                           without the "|". There is a maximum of 125 of these.
  118.                           If the "-f" option is not followed with a name,
  119.                           then file S:scan.config is used.
  120.  
  121.             ArtSep      - Article separator. Defaults to "\nArticle". Note
  122.                           that a "\" in the article separator has the same
  123.                           meaning as that in the pattern matching algorithm
  124.                           explained below. An article separator must be 2 or
  125.                           more characters long. For example, "\n\n" is a
  126.                           valid separator and causes a new article to be
  127.                           started with each blank line. Note that some shells
  128.                           require you to specify this as "\\n\\n".
  129.  
  130.    Options:
  131.  
  132.             -a            Article scan. Prints out all articles with matches.
  133.  
  134.             -cColumn      Column article separtor must be in(1..?).
  135.  
  136.             -fCnfgFile    Get parms from config file.
  137.  
  138.             -f            Get parms from s:scan.config.
  139.  
  140.             -hxy          Highlight match with x color and pathname, y color.
  141.  
  142.             -i            Invert matching so nonmatching articles are printed.
  143.  
  144.             -lxx          Line search with xx lines around target printed.
  145.  
  146.             -n            Print line numbers with matched text(slower).
  147.  
  148.             -oOutFile     Send output to file.
  149.  
  150.             -p            Always print file pathnames scanned.
  151.  
  152.             -r            Recursively scan down directories.
  153.  
  154.             -sArtSep      Article separator(def Article).
  155.  
  156.             -t            Truncate output to window width. Only works with -n.
  157.  
  158.             -v            Print version number. Other options nulled.
  159.  
  160.             -wWinSize     Window size(def 16384 bytes). Mod(size,4) must be 0.
  161.  
  162.             -x            Print out more help information. Nulls other options.
  163.  
  164.             -zWildPat     Enabl decomp of .lzh and .lha files with int files
  165.                           matching WildPat.
  166.  
  167.             -z            Enable decompression of all .lzh and .lha files.
  168.  
  169.    Pattern:
  170.    matching
  171.  
  172.             ?           Matches any single character except
  173.  
  174.             [chars]     Match any characters within braces. i.e. [abcxyz]
  175.  
  176.             [c1-c2]     Match any character from c1 to c2. i.e. [a-x]
  177.  
  178.             [^chars]    Match any characters not within the brackets.
  179.  
  180.             \xYY        Matches hex number YY as a character. Note that back
  181.                         slashes are preprocessed by some shells. You may need
  182.                         to put two slashes back to back to prevent this.
  183.  
  184.             \Y          Matches the standard C escape sequence Y
  185.  
  186.             \YYY        Matches the decimal number YYY as a character
  187.  
  188.             |           Finding the pattern on the left or right causes a match
  189.  
  190.             +           Same as |
  191.  
  192.             *           Pattern on left and right must both match and be in the
  193.                         same word. Match on left must come before one on right.
  194.  
  195.             &           Pattern on left and right must both match and be in the
  196.                         same sentence. Match on left must come before match on
  197.                         the right. A sentence is delimited by:
  198.  
  199.                         a) period followed by a space or line feed
  200.                         b) a maximum of OVERLAP(512) characters
  201.                         c) two newline chars with no chars but ">" between them
  202.                         d) start or end of article
  203.                         e) newline before a colon
  204.  
  205.             ..          Pattern on left and right must both match and be in the
  206.                         same article. Order of left and right matches is not
  207.                         important. This is faster than "&". This wildcard is
  208.                         only used during article scans(-a or -f), not line
  209.                         scans.
  210.  
  211.  
  212.    Config:
  213.    format
  214.  
  215.            line 1       Article separator
  216.  
  217.            line 2       Column article separator must be in. 0 -> ignore
  218.  
  219.            line 3       Invert match flag. 1 -> invert match. 0 -> normal
  220.  
  221.            line 4       Window size in bytes. Mod( size, 4 ) must be 0.
  222.  
  223.            line 5..129  Search patterns. There is an implicit "|" between
  224.                         each line. There may be fewer than 125 pattern lines
  225.                         if there are any ".." wildcards on a line. The number
  226.                         of lines is reduced directly by the number of ".."'s.
  227.  
  228.  
  229.    Background:
  230.  
  231.            I wrote "scan" to help minimize the time I spend scanning the
  232.            very large(megabyte) USENET proceedings I download weekly. This
  233.            program scans a file or set of files looking for strings matching
  234.            a user specified pattern(s). It supports the traditional *, ?, and
  235.            [] wildcards, but includes three new ones; "&" and "|" which are
  236.            similar to "*" but work on sentences and articles instead of words
  237.            and ".." which is similar to "&" but is order independent. "Scan"
  238.            can print out the entire text of an article if a match is found
  239.            anywhere in the article. It can search recursively down directories
  240.            and do inverse pattern matching where only articles that don't match
  241.            the pattern are printed out. Due to the size of Usenet proceedings,
  242.            it's desirable to keep them archived in compressed form. Scan
  243.            supports .LZH and .LHA formats with .LHA being significantly faster
  244.            and more dense. You can even selectively scan user specified
  245.            internal .LZH and .LHA files using a wildcard pattern. Finally, up
  246.            to 125 patterns can be scanned for simultaneously, with minimal
  247.            speed degradation.
  248.  
  249.            The fastest search programs I've seen to date are "zgrep" and the
  250.            "csh" search command. "Zgrep has the edge when run out of ram
  251.            but "csh" does better on hard disk searches. "Scan" searches twice
  252.            as fast as "csh" on harddrives and 3 times faster than "zgrep".
  253.            It searches 5 times faster than "zgrep" in ram and 15 times faster
  254.            than "csh" in ram. Search time is about the same for all 3 when
  255.            done off of the floppy.
  256.  
  257.  
  258.    Algorithm:
  259.  
  260.            A preprocessor selects the least repetitive two character
  261.            sub-pattern from each major term of the pattern. An even and an
  262.            odd two character subpattern is selected. This allows 16 bits
  263.            to be processed at a time in the inner loop. These two character
  264.            subpatterns are used to do a parallel Boyer-Moore type search.
  265.            If a match is found with the two char subpattern, the rest of
  266.            the pattern is checked. If the full major term matches, a flag is
  267.            set and other flags examined to see if the full minterm matches.
  268.            If so, another flag is set to cause the article to be printed out.
  269.            A triple buffer approach is used with Matt Dillons asynchronous
  270.            I/O to help speed file reads. Thanks Matt. A special two character
  271.            end of buffer subpattern is put at the end of the buffer so EOF
  272.            wont have to be checked for after each pattern check.
  273.  
  274.  
  275.    Examples:
  276.  
  277.            Searching for sentences with the words "Amiga" and "commercial"
  278.            in them is specified with:
  279.  
  280.                  amiga&commercial | commercial&amiga
  281.  
  282.            If "Amiga" and commercial don't have to be in the same sentence,
  283.            then it can be done with:
  284.  
  285.                  amiga..commercial
  286.  
  287.            To find the paragraphs with the words "truth" and "life" in them
  288.            within the Gospel of John, using the archived new testament on BIX,
  289.            with the "csh" shell, and printing out the internal book names as
  290.            they are scanned:
  291.  
  292.                  scan -aps\\n\\n "-z*john*" biblenew.lha truth..life
  293.  
  294.            This takes about 3 seconds off a harddrive on an A3000.
  295.  
  296.            Note also that to setup an alias in "csh" requires additional
  297.            back slashes:
  298.  
  299.                  alias scankjv "scan -as\\\\n\\\\n"
  300.  
  301.            To find all occurances of "faith" and "healed" in the same sentence
  302.            in the entire new testament, only printing out the names of the
  303.            books with the matches, highlighting the word that matched, and
  304.            printing 3 lines of context on both sides of the match:
  305.  
  306.                  scan -l3 -z biblenew.* faith&healed+healed&faith
  307.  
  308.  
  309.    Hints:  Search patterns must be at least 2 characters long.
  310.            There must be at least two consequtive unique characters
  311.            within each major term of the pattern. A major term is delimited
  312.            by a "|", "+", or "..". The program will tell you if it cannot
  313.            find unique subpatterns.
  314.  
  315.            There are four distinct command formats of Scan. The 1st is a
  316.            default format which scans for matching lines, not articles.
  317.            The 2nd format has a "-a" in it and scans for articles. The
  318.            3rd has a "-f" in it and also scans for articles, but it gets
  319.            most of its options from a configuration file. The 4th is used
  320.            to print the version or more help information.
  321.  
  322.            Specifying an article separator containing line feeds, can be
  323.            done by adding a "\n". Note that some command line interpreters
  324.            require an extra slash "\\n". For example, to specify a blank
  325.            line as an article separator with csh, use "-s\\n\\n".
  326.  
  327.            Command line options can be grouped together with the exception
  328.            of those having arguments. An option with an argument like "-l"
  329.            must appear with a separate dash or be the last option in a
  330.            dash group.
  331.  
  332.            Some CLI's, along with Scan, limit the command line to 255
  333.            characters. When doing wildcard file matching on the command
  334.            line, large numbers of matching files can cause a command line
  335.            overrun. This is not harmful, but some of the files you expected
  336.            to get scanned, won't be. The solution is to put quotes around
  337.            the wildcards.
  338.  
  339.            The filename pattern matching algorithm is alot faster than the
  340.            one in "csh" and probably other shells. Because of this, it is
  341.            alot faster to do:
  342.  
  343.                  scan "dh0:work/*" xyz
  344.  
  345.            than to do:
  346.  
  347.                  scan dh0:work/* xyz
  348.  
  349.            especially if there are alot of files in the directory.
  350.  
  351.  
  352.    Source: This is a gamma test version of the program "scan". Once I have
  353.            received enough bug notifications and suggestions, I will release
  354.            the source.
  355.  
  356.    Author: Walter Rothe
  357.  
  358.    Contact: BIX - aimania     OR     2008 Mary St, Carrollton, Tx 75006
  359.  
  360.  
  361.  
  362.